</section>
<section id="The_Solution">
<title>The Solution</title>
- <para> I needed to convert waypoints between a couple of formats, so I
+ <para> The original author of GPSBabel, <ulink url="/people/robertlipe.html">Robert Lipe</ulink>, needed to convert waypoints between a couple of formats, so he
whipped up a converter and based it on an extensible foundation so
-that it was easy to add new formats. Most file formats added so far
-have taken under 200 lines of reasonable ISO C so they can be stamped
-out pretty trivially. Formats that are ASCII text delimited in some
-fixed way can be added with no programming at all via our 'style'
-mechanism.
-</para>
+that it was easy to add new formats and made the program freely available. <ulink url="/people/index.html">Many others</ulink> have contributed to the program since then.</para>
+ <para> Most file formats added so far have taken under 200
+ lines of reasonable ISO C so they can be stamped
+ out pretty trivially. Formats that are ASCII text delimited in some
+ fixed way can be added with no programming at all via our
+ <link linkend ="Styles">style</link> mechanism.
+ </para>
</section>
</preface>
<title>Usage</title>
<sect1 id="Invocation">
<title>Invocation</title>
- <para>Invocation was meant to be flexible. Unfortunately,
- that can sometimes lead to unwieldy command lines.</para>
-
<para>
If you're using GPSBabel, you will need to know how to do at least two things:
read data from a file, and write it to another file. There are four basic
-commands you need to know to do those things:
+options you need to know to do those things:
</para>
<segmentedlist>
<?dbhtml list-presentation="table"?>
parentheses.
</para>
<para>
+Options are <emphasis>always</emphasis> processed in order from left to right.
+In practical terms, this means that things you want to read should appear
+in the command before things you want to write.
+</para>
+<para>
The <parameter class="command">filename</parameter> parameters specify the
name of a file to be read or written.
</para>
<screen format="linespecific"> gpsbabel -s -i geo -f geocaching.loc -o magellan -F /dev/ttyS0 </screen>
<screen format="linespecific"> gpsbabel -s -i geo -f geocaching.loc -o magellan -F com1</screen>
</sect1>
+ <sect1 id="Suboptions">
+ <title>Suboptions</title>
+ <para>
+ Many of the available format options in GPSBabel can themselves
+ take options. While we try to make all the formats do the most
+ sensible thing possible without any extra options, this allows
+ great power and flexibility in the operation of the program.
+ </para>
+ <para>
+ Suboptions are comma separated and immediately follow the option
+ itself. The available suboptions are listed on the individual
+ format pages. We'll make an example from <xref linkend="fmt_kml" />:
+ </para>
+ <screen format="linespecific">gpsbabel -i gpx -f file.gpx -o kml,deficon="file://myicon.png",lines=0 -F one.kml -o kml -F two.kml</screen>
+ <para>
+ This command will read the GPX file <filename>file.gpx</filename>
+ and create two KML files. <filename>one.kml</filename> will
+ have the given icon and no lines between track and routepoints.
+ <filename>two.kml</filename> will be created with the defaults used
+ in the KML writer.
+ </para>
+ <para>
+ Suboptions for the various formats allow you to change serial speeds,
+ pass arguments to filters, change the type of file written, override
+ icon defaults, and lots of other things. The suboptions for each
+ filetype are documented on the page in this document that describes
+ the option itself.
+ </para>
+ </sect1>
<sect1 id="Advanced_Usage">
<title>Advanced Usage</title>
<para>Argument are processed in the order they appear on the command
</sect1>
<sect1 id="Route_And_Track_Modes">
<title>Route and Track Modes</title>
- <para> Most formats will make reasonable attempt to work
+ <para> Most formats will make a reasonable attempt to work
transparently with waypoints, tracks, and routes. Some
formats, like 'garmin' and 'magellan' require the <parameter moreinfo="none">-t</parameter> flag to work with tracks and
<parameter moreinfo="none">-r</parameter> to work with
to handle every possible hazard that can be encountered
during a conversion. If you're merging or converting files
of similar limitations, things work very well.</para>
+ <para> Many of those hazards can be overcome with our filters
+ but there are often compromises to be made. For example, if you
+ have a GPX route that contains 150 turn points but you're sending
+ the route to a GPX that supports only 30 turnpoints, something has
+ to go. One might use our 'simplify' filter to produce a route that
+ retained the 30 most mathematically significant turnpoints but that
+ may not really be the route you had in mind.
+ </para>
<para> Tracks and routes will sometimes be converted to a
list of waypoints when necessary, f.i. when writing into one
of the CSV formats. The inverse operation is not supported
<para>
-These data files are "character" separated text files like
+<productname>CompeGPS</productname> data files are "character" separated text files like
the pcx format. "Character" means special data lines can have their
own separator.
</para>
<para>
-Garmin Training Center is the successor to Garmin' Logbook program
-for their workout units. It is a free upgrade.
+GPSBabel has limited support for Garmin Training Center files. That program is the successor to Garmin' Logbook program for their workout units. It is a free upgrade.
</para>
<para>
This format is somewhat underachieving in GPSBabel. It is a write-only
- <para> HTML output generates a single HTML file of all of the
+ <para> GPSBabel's HTML output generates a single HTML file of all of the
waypoints in the input file. It supports a number of Groundspeak GPX
-extensions, as well as filters out potentially harmful HTML from the
-input file while maintaining almost all of the source HTML formatting.
+extensions and filters out potentially harmful HTML from the
+input file while maintaining almost all of the source HTML formatting.
+This makes this format well suited for generating HTML to hand to programs
+like Plucker for putting in a PDA and especially so for "paperless caching"
+for Geocachers with pocket queries.
+</para>
+<para>This format is similar to the <link linkend="fmt_text">text</link> format.
</para>
<para> The following command line reads a GPX file with
Groundspeak extensions and writes an HTML file with encrypted hints
a file, either on local filesystem or on a mounted flash card reader,
will result in the file-based format being used.
</para>
+<para>
+ Users of the Explorist generation of receivers should probably
+ prefer to use the <link linkend="fmt_magellan">magellanx</link>
+ format over this one.
+
+</para>
<para>
This is the SD card format used by the <ulink url="http://www.magellangps.com">Magellan</ulink> Explorist 400,
- 500, 600, and XL and internally on those devices plus the
- Explorist 210. Storeed waypoints are identical to the Magellan SD format
+ Explorist 500, Explorist 600, and Explorist XL and internally on those devices plus the
+ Explorist 210. Stored waypoints are identical to the <link linkend="fmt_magellan">Magellan SD format</link>
used by Meridian, but the newer models allow longer waypoint names. Routes are
subtly different.
</para>
- <para> The SD card format used by the <ulink url="http://www.magellangps.com">Magellan</ulink> > 400,
-500, 600, 210, and XL to describe geocaches. Notice what while the format can
+ <para> This format support the on-card format used by the <ulink url="http://www.magellangps.com">Magellan</ulink> Explorist 400,
+Explorist 500, Explorist 600, Explorist 210, and Explorist XL
+to describe geocaches. Notice what while the format can
hold an infinite number of geocaches, the unit will read and silently
discard all but 200 geocache POIs at a time.</para>
<para> You should name any file created with this format with a
<para>Reads and writes places files for
-use in <ulink url="http://www.topomappro.com">TopoMapPro places files</ulink>). As this file
+use in <ulink url="http://www.topomappro.com">TopoMapPro places files</ulink>. As this file
type can store links other than web links, anything that is not a http
url will be discarded. Note that this does not do datum conversions,
so if your input file does not have WGS84/NZGD2000 data, your output
projects / gpsbabel.git / commitdiff